home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 2 / Atari Mega Archive CD - Volume 2.iso / 8bit / cislib_a / getchr.doc < prev    next >
Text File  |  1995-04-22  |  3KB  |  72 lines
  1. GETCHAR FOR VERSION 2
  2.  
  3. Just when you thought it was safe to go back to the compiler-
  4. -IT has returned..."Char Wars II:  The GetChar Strikes Back!"
  5.  
  6. A routine that waits for a single key to be pressed and 
  7. returns its value is one of the most popular programming 
  8. routines around.  Back in the March/April issue of the 
  9. UPDATE...KYAN newsletter, a Pascal GetChar routine and an 
  10. assembly language GetChar procedure both appeared, and the 
  11. latter was somewhat more useful.  The assembly language 
  12. GetChar procedure was written for use with Version 1.- of 
  13. Kyan Pascal and therefore will not work with Version 2.-.
  14.  
  15. For those of you who are having a hard time converting the 
  16. assembly language from Version 1.- to Version 2.-, I have 
  17. written a new GetChar function.  It uses the  CIOEqu.i 
  18. include file, available in this data library--see CIOEQU.DOC 
  19. and CIOEQU.PAS, for convenience.  GetChar is called like 
  20. this:
  21.  
  22.     Status := GetChar(Ch,Write_It);
  23.  
  24. Programming Techniques  Used by GetChar
  25.  
  26. The first parameter passed to GetChar is a character variable 
  27. which will be changed to reflect the key that the user 
  28. presses.  The second parameter is a boolean, and it instructs 
  29. GetChar whether or not to write the key that was pressed to 
  30. the screen (TRUE to write it, FALSE if you don't want the 
  31. character echoed to the screen).
  32.  
  33. Since GetChar uses CIO, I made it a function that will return 
  34. the CIO status byte (picked up from the Y register after a 
  35. JSR CIOV instruction).  The English error message translation 
  36. of the status byte number can be found in Appendix D of the 
  37. Kyan Pascal manual.  Just remember that a value of one (1) 
  38. indicates everything is all right--if it returns another 
  39. value something probably went wrong and you should inform the 
  40. user of the error and/or have your program try again.
  41.  
  42. The assembly code of GetChar first EQUates labels that are 
  43. for use with the stack pointer.  By doing this, these equates 
  44. can easily be changed if the parameter list were to be 
  45. changed instead of having to go through the entire routine, 
  46. replacing stack pointer numbers.
  47.  
  48. It then goes on to temporarily store the Key variable in _t+1 
  49. and _t+2.  Next, IOCB number one is closed and then opened, 
  50. so if it was open when GetChar was called, there could be 
  51. trouble.  The compiler always uses the standard IOCB zero for 
  52. E: and IOCB6 for S:, so there should be no problem unless you 
  53. have a file open.  The GetChar routine in the System 
  54. Utilities Toolkit contains a similar GetChar function that 
  55. takes care of this problem by finding a free IOCB.
  56.  
  57. Next, CIO is instructed to get one byte from the keyboard, 
  58. K:.  If an error occurs during this read operation (or back 
  59. when the file was opened), GetChar will branch to the end, 
  60. close the IOCB, and return the error number.  The byte that 
  61. was read is stored in the appropriate location using the 
  62. stack pointer, and then GetChar exits its assembly language 
  63. portion (notice how it jumped over the data bytes for the 
  64. device name--this is because if they are encountered as an 
  65. instruction, all sorts of fun things could happen during 
  66. runtime [for instance, my 130XE just plain locked up and shut 
  67. down before I figured out the problem and debugged it]).
  68.  
  69. (After downloading GETCHR.PAS, you should rename it to 
  70. GETCHAR.I on your disk.)
  71.  
  72.